<!--
 ~ Copyright (c) 2005-2010, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
 ~
 ~ WSO2 Inc. licenses this file to you under the Apache License,
 ~ Version 2.0 (the "License"); you may not use this file except
 ~ in compliance with the License.
 ~ You may obtain a copy of the License at
 ~
 ~    http://www.apache.org/licenses/LICENSE-2.0
 ~
 ~ Unless required by applicable law or agreed to in writing,
 ~ software distributed under the License is distributed on an
 ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ~ KIND, either express or implied.  See the License for the
 ~ specific language governing permissions and limitations
 ~ under the License.
 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
    <head>
        <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"/>
        <title>WS-Discovery Control Panel - User Guide</title>
        <link href="../../admin/css/documentation.css" rel="stylesheet" type="text/css" media="all"/>
    </head>
    <body>
        <h1>WS-Discovery</h1>
        <p>
            Web Services Dynamic Discovery protocol (WS-Discovery) is a standard mechanism for locating
            services and service endpoints in a SOA. The simplest and most common scenario for WS-Discovery
            is a Web Services client searching for one or more target services. The protocol specification
            outlines two modes of operation for WS-Discovery.
        </p>
        <ul>
            <li>Ad-hoc mode: Uses UDP multicast to advertise and discover services</li>
            <li>Managed mode: Uses HTTP unicast to advertise and discover services</li>
        </ul>
        <p>
            WSO2 Carbon provides a complete implementation of the WS-Discovery managed mode. With WS-Discovery
            components for WSO2 Carbon, any Carbon server can act as a WS-Discovery client, a WS-Discovery proxy
            or a WS-Discovery target service. Discovered services and related metadata are stored in a governance
            registry using governance interface of WSO2 Carbon. Therefore such information is also accessible via
            the service governance UI of Carbon as well.
        </p>
        <p>&#160;</p>
        <h2>
            WS-Discovery Control Panel
        </h2>
        <p>
            The WS-Discovery Control Panel for Carbon can be used to command and control the client side aspects
            of WS-Discovery. It can be used to connect to remote WS-Discovery proxies and probe them for any
            services and service endpoints which have been already discovered. The control panel also enables
            you to easily convert a discovered endpoint into an address endpoint configuration which can be
            processed by endpoint and mediation components of WSO2 Carbon. With this feature in place one can easily
            construct mediation sequences and proxy services using the endpoints discovered through WS-Discovery.
        </p>
        <p>
            To access the WS-Discovery Control Panel select Configure > WS-Discovery from the left navigation panel
            of the Carbon management console. The following page will be displayed.
        </p>
        <div class="image">
            <img src="images/discovery-home.png" alt="Discovery Home"/>
        </div>
        <p>Figure 1: WS-Discovery Control Panel (Discovery Home Page)</p>
        <p>&#160;</p>
        <h2>
            Setting Up a WS-Discovery Proxy Configuration
        </h2>
        <p>
            For Carbon to be able to connect to a remote WS-Discovery proxy and make use of the endpoints discovered
            by the proxy, you first need to create a WS-Discovery proxy configuration.
            Click on <strong>Add Discovery Proxy</strong> option on the Discovery control panel. You will be taken
            to the <strong>Configure WS-Discovery Proxy</strong> page.
        </p>
        <div class="image">
            <img src="images/config-proxy.png" alt="Discovery Home"/>
        </div>
        <p>Figure 2: WS-Discovery Proxy Configuration</p>
        <p>
            Specify a preferred name for the remote discovery proxy. Then specify the URL over which the remote
            proxy can be reached. If the remote discovery proxy is secured using WS-Security you need to first
            upload the client security policy to the configuration registry of Carbon and then point to it in the
            discovery proxy configuration page. Having entered all the required parameters click on 'Save' to
            save the settings to the underlying registry. You will be taken back to the WS-Discovery control panel
            home page, and this time you will notice the newly created WS-Discovery proxy configuration is listed
            there.
        </p>
        <div class="image">
            <img src="images/proxy-list.png" alt="Discovery Home"/>
        </div>
        <p>Figure 3: WS-Discovery Control Panel (List of Proxies)</p>
        <p>
            To modify an existing WS-Discovery proxy configuration select the 'Edit' option. This will take you
            back to the <strong>Configure WS-Discovery Proxy</strong> page, where you can make the necessary
            changes to the configurations. If you want to permanently delete a proxy configuration simply select
            the 'Delete' option.
        </p>
        <p>&#160;</p>
        <h2>
            Browsing Discovered Services
        </h2>
        <p>
            From the WS-Discovery control panel select the discovery proxy to which you wish to connect and click
            on the 'View' option. Note that you can only do this for a proxy whose status is 'On-Line'. This will
            send a WS-Discovery probe to the remote proxy and retrieve all the services discovered by the proxy.
            The retrieved information will then be displayed as follows on the <strong>Target Services and
            Endpoints page</strong>.
        </p>
        <div class="image">
            <img src="images/service-browser.png" alt="Target Services and Endpoints"/>
        </div>
        <p>Figure 4: Target Services and Endpoints</p>
        <p>
            If the remote proxy is configured to return the insactive services, they will also be displayed on the
            above view. You can further refine the results by the entering a search query in the 'Search by Scopes'
            search box. Enter either a single scope (URI) or a comma separated list of scopes to short list the
            result set displayed. Each search will trigger a WS-Discovery probe to the remote proxy.
        </p>
        <p>
            To get more information on a service, simply click on the service ID in the <strong>Target Services and
            Endpoints</strong> page. This will take you to the target
            service view. You can see the exact types, scopes, endpoints and transports of the service. A WS-Discovery
            resolve request is sent to the discovery proxy to obtain the necessary data.
        </p>
        <div class="image">
            <img src="images/target-service.png" alt="Target Service"/>
        </div>
        <p>Figure 4: Target Service View</p>
        <p>
            The target service view also allows you to construct mediation endpoints out of the endpoints of the
            target service. Such mediation endpoints can then be used in mediation sequences and proxy services.
            To create a mediation endpoint click and expand the <strong>Create ESB Endpoints</strong> panel. Please
            note that this panel will be displayed only if the endpoint UI component is installed in the Carbon
            server.
        </p>
        <div class="image">
            <img src="images/create-endpoint.png" alt="Create Endpoints"/>
        </div>
        <p>Figure 4: Create Endpoints Panel</p>
        <p>
            Enter a name for the mediation endpoint, select a target address and click on 'Save' to create the
            endpoint. You can then browse to Manage > Endpoints view or Configure > Synapse view to see the
            newly constructed mediation endpoint and do the necessary changes to the endpoint configuration.
        </p>
    </body>
</html>